Clasificación de Imágenes por Propósito Accesible
⚠️ Actualmente no está en producción. Este checkpoint no forma parte del producto en vivo por ahora: los modelos de clasificación de imágenes en los que se apoyaba fueron discontinuados. Su integración está prevista para una próxima versión.
Este documento explica la lógica que sigue el test de clasificación de imágenes y el prompt utilizado para la clasificación mediante inteligencia artificial.
Tabla de Contenidos
- Visión General
- Flujo del Test
- El Prompt de Clasificación
- Metodología de Análisis por Capas
- Tipos de Clasificación
- Reglas Críticas
- Análisis de Calidad del Texto Alternativo
Visión General
El sistema de clasificación de imágenes utiliza una combinación de análisis de IA y reglas heurísticas para clasificar imágenes en una página web según su propósito accesible, siguiendo las directrices WCAG 2.1 y los tutoriales W3C WAI. El sistema clasifica las imágenes en tres categorías:
- ACTIVE (Activa): Imágenes funcionales que inician acciones o actúan como controles interactivos
- INFORMATIVE (Informativa): Imágenes que transmiten información esencial
- DECORATIVE (Decorativa): Imágenes puramente ornamentales o redundantes
Flujo del Test
1. Extracción de Elementos de Imagen
El test comienza extrayendo todos los elementos de imagen de la página web desde dos fuentes:
1.1 Árbol de Accesibilidad (AXTree)
- Se obtiene el árbol completo de accesibilidad de la página
- Se buscan nodos con roles:
image,img,graphics-symbol - Se identifican elementos con etiquetas:
img,svg - Se detectan nodos ignorados con razón
emptyAlt(probablemente imágenes decorativas) - Se extraen atributos clave:
alt,aria-hidden,role,name
1.2 DOM (Document Object Model)
- Se buscan elementos adicionales que no fueron capturados por el AXTree
- Se identifican elementos
<img>,<svg>, y<input type="image"> - Se detectan elementos con
role="img" - Se extraen atributos directamente del DOM
2. Enriquecimiento de Contexto
Para cada elemento de imagen encontrado, se enriquece con información contextual:
- elementOuterHTML: El HTML completo del elemento (máximo 250 caracteres)
- parentOuterHTML: El HTML del elemento padre (si está disponible)
- containerOuterHTML: El HTML del contenedor (como alternativa al padre)
- interactiveAncestor: Información sobre el ancestro interactivo más cercano (si existe)
tagName: Etiqueta del ancestrorole: Rol del ancestroaccessibleName: Nombre accesible del ancestroariaLabel: Etiqueta ARIA del ancestrotextContent: Contenido de texto del ancestroouterHTML: HTML del ancestro
3. Captura de Captura de Pantalla
- Se captura una captura de pantalla completa de la página
- Se convierte a formato PDF para su análisis por la IA
- El PDF contiene la representación visual completa de la página
4. Procesamiento por Lotes
Los elementos se procesan en lotes de 50 elementos para optimizar el uso de tokens y mejorar la eficiencia:
batch_size = 50
for batch_idx in range(0, total_elements, batch_size):
batch_elements = enriched_elements[batch_idx : batch_idx + batch_size]
# Procesar lote...5. Análisis con IA
Para cada lote:
- Creación del Prompt: Se genera un prompt detallado con toda la información contextual de los elementos del lote
- Análisis Visual: La IA analiza el PDF (captura de pantalla) junto con el prompt
- Clasificación: La IA clasifica cada imagen como ACTIVE, INFORMATIVE o DECORATIVE
- Evaluación de Calidad: La IA evalúa la calidad del texto alternativo comparándolo con el contenido visual
6. Procesamiento de Resultados
Después de recibir los resultados de la IA, el sistema:
- Parsea la Respuesta: Extrae los resultados de clasificación del JSON devuelto por la IA
- Aplica Reglas de Prioridad: Sobrescribe la clasificación de la IA según reglas críticas:
- Si
aria-hidden="true"orole="presentation"→ DECORATIVE (prioridad absoluta) - Si
input[type="image"]→ ACTIVE (siempre activo, a menos que tengaaria-hidden="true")
- Si
- Resuelve Texto Alternativo: Obtiene el texto alternativo desde múltiples fuentes (AXTree, DOM, atributos)
- Genera Reportes: Crea reportes de accesibilidad para cada imagen clasificada
7. Generación de Reportes
Para cada imagen clasificada, se genera un reporte que incluye:
- Clasificación final (ACTIVE, INFORMATIVE, DECORATIVE)
- Nivel de confianza (high, medium, low)
- Razonamiento de la clasificación
- Calidad del texto alternativo (good, needs_improvement, missing)
- Puntuación de accesibilidad (0-10)
- Recomendaciones específicas
- Metadatos (backendId, uniqueId, source, etc.)
El Prompt de Clasificación
El prompt es una instrucción detallada que se envía a la IA para guiar el proceso de clasificación. Está diseñado para asegurar una precisión del 99.9% siguiendo un orden estricto de análisis.
Estructura del Prompt
El prompt contiene las siguientes secciones principales:
- Instrucción Principal: Define el rol del experto y el objetivo
- Reglas Críticas: Orden estricto de aplicación para máxima precisión
- Metodología de Análisis por Capas: Proceso paso a paso obligatorio
- Tipos de Clasificación: Definiciones detalladas de cada categoría
- Ejemplos Contextuales: Casos de uso comunes
- Análisis de Calidad del Texto Alternativo: Criterios de evaluación
- Casos Especiales: Manejo de situaciones límite
- Formato de Salida: Estructura JSON requerida
Contenido del Prompt
Instrucción Principal
You are a web accessibility expert classifying images on a webpage based on WCAG 2.1
and W3C WAI tutorials. Analyze the provided PDF document which contains a full page
screenshot of the webpage. Review the PDF document carefully to examine the visual
content and context of each image, then classify each image as ACTIVE, INFORMATIVE,
or DECORATIVE.Reglas Críticas (Orden Estricto)
El prompt establece 4 reglas críticas que deben aplicarse en orden estricto:
- Precedencia de ARIA-HIDDEN: Si
aria-hidden="true"está presente en CUALQUIER capa → DECORATIVE (sobrescribe todo) - Regla Especial INPUT TYPE="IMAGE": Los elementos
<input type="image">son SIEMPRE ACTIVE (a menos que tenganaria-hidden="true") - Marcadores Decorativos: Si
ariaHidden=true,rolePresentation=true, oaltText=""→ DECORATIVE - Principio Fundamental: Clasificar basándose en CONTENIDO VISUAL + CONTEXTO, no solo en texto alternativo
Metodología de Análisis por Capas
El prompt define una metodología de análisis en 4 capas que debe seguirse estrictamente:
Capa 1: Análisis de elementOuterHTML
- Parsear el string
elementOuterHTML(si está disponible) - Extraer atributos:
aria-hidden→ si "true", clasificar como DECORATIVE (DETENER)- Para elementos input:
type→ si "image", clasificar como ACTIVE inmediatamente alt→ verificar si está vacío o norole→ verificar rol de presentación- Estructura del elemento → determinar si es interactivo por naturaleza
Capa 2: Análisis de parentOuterHTML/containerOuterHTML
- Si la Capa 1 no proporcionó información completa:
- Parsear
parentOuterHTML(preferido) ocontainerOuterHTML(alternativa) - Buscar el elemento dentro del HTML padre/contenedor usando
uniqueIdodata-unique-id - Extraer los mismos atributos que en la Capa 1
- Verificar contexto circundante (elementos hermanos, estructura padre)
- Parsear
Capa 3: Análisis de Ancestro Interactivo
- Si
interactiveAncestorestá presente:- Parsear
interactiveAncestor.outerHTMLpara entender el contexto interactivo - Determinar si la imagen es el contenido único o contenido suplementario
- Evaluar si la imagen impulsa la interactividad (→ ACTIVE) o es decorativa (→ DECORATIVE)
- Parsear
Capa 4: Análisis Visual y Contextual
- Examinar el documento PDF para el contenido visual de cada imagen
- Revisar la captura de pantalla dentro del PDF para entender el contexto visual
- Verificar texto cercano en el contexto HTML y en el documento PDF
- Evaluar si el texto describe completamente la imagen (→ DECORATIVE) o omite información clave (→ INFORMATIVE)
Pasos de Análisis (Seguir Estrictamente)
Revisión de OuterHTML por Capas:
- CAPA 1: Parsear
elementOuterHTMLparaaria-hidden="true"(→ DECORATIVE). Para tagName "input" o si el elemento contiene<input, extraer atributotype—sitype="image"→ ACTIVE (detener aquí, atributo alt no requerido). - CAPA 2: Si la Capa 1 está incompleta, parsear
parentOuterHTMLocontainerOuterHTMLpara localizar el elemento input real. Buscar etiquetas<inputy verificartype="image"→ ACTIVE (detener aquí, atributo alt no requerido).
- CAPA 1: Parsear
Verificación de Nombre Accesible (CRÍTICO PARA INFORMATIVE):
- Verificar nombre accesible: atributo
alt(no vacío),aria-label,aria-labelledby, atributotitle, o nombre accesible del camponame. - Si NO se encuentra nombre accesible → NO PUEDE ser INFORMATIVE, clasificar como DECORATIVE (a menos que sea ACTIVE por reglas especiales).
- Verificar nombre accesible: atributo
Verificación de Etiqueta/Contexto: Confirmar reglas especiales (ej., input[type="image"] → ACTIVE, independientemente del atributo alt).
Evaluación de Estructura: ¿Es la imagen el único contenido interactivo? (→ ACTIVE) ¿O es suplementario/redundante? (→ DECORATIVE/INFORMATIVE)
Contexto de Texto: ¿El texto cercano describe completamente la imagen? (→ DECORATIVE) ¿O omite información clave? (→ INFORMATIVE, pero SOLO si tiene nombre accesible del paso 2).
Revisión Visual: Revisar el documento PDF para examinar cada imagen visualmente. Formas/patrones decorativos (→ DECORATIVE); visuales significativos (→ INFORMATIVE, pero SOLO si tiene nombre accesible del paso 2).
Evaluación de Calidad del Texto Alternativo:
- Comparar el contenido visual de la imagen (del documento PDF) con el texto alternativo o nombre accesible.
- Determinar si el texto alternativo describe con precisión lo que se muestra en la imagen.
- Considerar contexto: las imágenes decorativas deben tener texto alternativo vacío, las imágenes funcionales necesitan descripción de propósito, las imágenes informativas necesitan texto alternativo que transmita la información esencial.
Marcadores/Verificación: Verificar cruzadamente metadatos, pero priorizar el análisis de outerHTML por capas.
Tipos de Clasificación
1. ACTIVE (Funcional)
Las imágenes ACTIVE son aquellas que inician una acción, actúan como hipervínculo, controlan la interfaz o modifican la comprensión de una interacción.
Prerequisito: Para ser clasificada como ACTIVE, el elemento (img, svg) DEBE tener un nombre accesible (alt, aria-label, aria-labelledby, o title). Si carece de esto, cae a DECORATIVE inmediatamente.
Categorías de Imágenes ACTIVE:
- Contenido Interactivo Único: La imagen es el único contenido dentro de un enlace (
<a>) o botón (<button>). Ejemplos: Un icono de lupa para "Buscar", un icono de impresora, o un logo de empresa que enlaza a la página de inicio. - Modificadores Funcionales: Imágenes dentro de enlaces/botones que aparecen junto con texto PERO proporcionan contexto esencial sobre el comportamiento o formato de la interacción que el texto NO establece explícitamente.
- Ejemplos: Un icono que indica "se abre en nueva ventana", "enlace externo", "descargar", o tipo de archivo (ej., un icono PDF junto a "Informe Anual").
- Controles de Entrada: Imágenes usadas como entradas de formulario (ej.,
<input type="image">). - Indicadores de Estado: Iconos que representan un estado no descrito por texto (ej., un icono de nivel de batería, un icono de estrella para "favorito").
Regla Especial: Los elementos <input type="image"> son SIEMPRE ACTIVE porque funcionan como botones de envío, independientemente de si tienen un atributo alt o no. Esta es un requisito W3C/WCAG.
2. INFORMATIVE (Informativa)
Las imágenes INFORMATIVE transmiten un concepto simple, emoción o información que NO está completamente transmitida por el texto adyacente.
Requisito Crítico: Una imagen es INFORMATIVE SOLO si AMBAS (1) agrega valor/significado distinto Y (2) tiene un nombre accesible (texto alternativo, aria-label, title). Si una imagen transmite significado visualmente pero carece de nombre accesible, clasificar como DECORATIVE (tratar como un fallo técnico donde la imagen se vuelve invisible para las tecnologías de asistencia).
Patrones de Imágenes INFORMATIVE:
- Distingue elementos (icono de teléfono vs. icono de fax) CON nombre accesible.
- Complementa texto (foto no descrita) CON nombre accesible.
- Muestra acciones (diagramas) CON nombre accesible.
- Indica tipo (icono PDF si el texto omite "(PDF)") CON nombre accesible.
Ejemplos:
- Gráfico con datos + texto alternativo
- Logo CON texto alternativo/aria-label
- Icono PDF + "Descargar informe" + texto alternativo
- Iconos de estado CON nombres accesibles
NO es INFORMATIVE:
- Logos sin texto alternativo/aria-label (→ DECORATIVE)
- SVGs en enlaces etiquetados que no agregan información (→ DECORATIVE)
- Imágenes sin nombre accesible que no agregan valor más allá del contexto (→ DECORATIVE)
3. DECORATIVE (Decorativa)
Las imágenes DECORATIVE son puramente ornamentales o redundantes; eliminarlas no afectaría la comprensión del contenido por parte del usuario.
Patrones de Imágenes DECORATIVE:
- Embeleza (bordes, patrones).
- El texto cubre completamente (foto + descripción completa).
- Estilo repetitivo (flechas de lista).
- Suplementario en controles etiquetados.
- Carece de nombre accesible (sin texto alternativo, sin aria-label, sin title) y no agrega valor más allá del contexto (ej., SVG en enlace etiquetado, logo sin texto alternativo).
- No agrega información más allá de lo que ya transmite el texto/estructura cercana.
Ejemplos:
- Separadores
- Gradientes
- Icono + "Descargar (PDF)"
- Elementos con aria-hidden
- Logos sin texto alternativo/aria-label
- SVGs en enlaces/botones etiquetados que no agregan información
- Imágenes sin nombre accesible que son redundantes al contexto
Reglas Críticas
Regla 1: Precedencia de ARIA-HIDDEN
Prioridad Absoluta: Realizar ANÁLISIS POR CAPAS—escaneando TODO el outerHTML disponible en orden: primero elementOuterHTML, luego parentOuterHTML o containerOuterHTML, y finalmente interactiveAncestor.outerHTML si está disponible. Buscar aria-hidden="true" en CUALQUIER capa. Si está presente EN CUALQUIER LUGAR, clasificar como DECORATIVE inmediatamente—sobrescribe todo lo demás.
Regla 2: INPUT TYPE="IMAGE" (SIEMPRE ACTIVE)
Análisis por Capas para Detectar input[type="image"]:
- CAPA 1 - elementOuterHTML: Si
tagNamees "input" O sielementOuterHTMLcontiene una etiqueta<input, parsear el string HTML para extraer:- Buscar
type="image"otype='image'(sin distinción de mayúsculas/minúsculas) - Si se encuentra
type="image", clasificar como ACTIVE inmediatamente—independientemente de otros factores (incluyendo presencia o contenido del atributo alt).
- Buscar
- CAPA 2 - parentOuterHTML/containerOuterHTML: Si la Capa 1 no encontró el elemento input (ej.,
elementOuterHTMLpodría estar faltando o incompleto), parsearparentOuterHTMLocontainerOuterHTMLpara localizar el elemento<input>real. Buscar:- Etiquetas
<inputdentro del HTML padre/contenedor - Verificar cada input para
type="image"otype='image'(sin distinción de mayúsculas/minúsculas, el orden de atributos no importa) - Si se encuentra con
type="image", clasificar como ACTIVE inmediatamente.
- Etiquetas
Ejemplos que DEBEN ser detectados como ACTIVE:
<input type="image" src="search.png">→ ACTIVE (incluso sin alt)<input type="image" src="search.png" alt="Search">→ ACTIVE<input name="submit" src="..." type="image">→ ACTIVE (el orden de atributos no importa, incluso sin alt)<input name="submit" src="/path/to/image.png" type="image" style="...">→ ACTIVE (incluso con otros atributos, incluso sin alt)
CRÍTICO: Los elementos input[type="image"] son SIEMPRE ACTIVE porque funcionan como botones de envío, independientemente de si tienen un atributo alt o no. Este es un requisito W3C/WCAG.
Regla 3: Marcadores Decorativos
Si ariaHidden=true, rolePresentation=true, o altText="" (cadena vacía, verificado en outerHTML), clasificar como DECORATIVE.
Regla 4: Principio Fundamental
Para casos no especiales, clasificar basándose en CONTENIDO VISUAL + CONTEXTO (texto/estructura cercana). NO confiar únicamente en el texto alternativo—muchas imágenes decorativas tienen texto alternativo incorrecto que debería eliminarse.
Análisis de Calidad del Texto Alternativo
El prompt incluye instrucciones detalladas para evaluar la calidad del texto alternativo comparándolo con el contenido visual de la imagen.
Campo DESCRIBES_IMAGE (True/False)
- True: El texto alternativo o nombre accesible describe con precisión el contenido visual esencial o la función de la imagen
- False: El texto alternativo falta, está vacío (cuando no debería estarlo), es inexacto, o no transmite la información esencial
Campo ALT_TEXT_QUALITY_EXPLANATION
Proporcionar una explicación detallada que cubra:
- Qué muestra la imagen visualmente (basado en la revisión del documento PDF)
- Qué dice el texto alternativo (desde campos altText, name, o nombre accesible)
- Si coinciden y por qué
- Consideraciones de contexto (las imágenes decorativas deben tener texto alternativo vacío, las imágenes funcionales necesitan descripción de propósito, las imágenes informativas necesitan texto alternativo que transmita la información esencial)
Directrices de Evaluación de Calidad
- Imágenes DECORATIVE: Deben tener texto alternativo vacío (
alt="") oaria-hidden="true". Si tienen texto alternativo descriptivo, establecerdescribes_image: falsey explicar que las imágenes decorativas no deberían tener texto alternativo. - Imágenes ACTIVE: El texto alternativo debe describir la función/acción, no necesariamente la apariencia visual. Ej., "Buscar" no "Icono de lupa".
- Imágenes INFORMATIVE: El texto alternativo debe transmitir la información esencial mostrada en la imagen. Ej., "Las ventas aumentaron 25% de Q1 a Q2" no solo "Gráfico de barras".
- Texto alternativo faltante: Siempre establecer
describes_image: falsecuando el texto alternativo falta para imágenes ACTIVE o INFORMATIVE. - Texto alternativo genérico: Texto alternativo como "imagen", "foto", "icono" sin descripción específica debe ser
describes_image: false.
Ejemplos Contextuales
El prompt incluye numerosos ejemplos para guiar la clasificación:
Ejemplos de Clasificación
- PDF icon + "Download report" + alt text → INFORMATIVE (agrega formato, tiene nombre accesible)
- PDF icon + "Download report" SIN alt text/aria-label → DECORATIVE (carece de nombre accesible, no puede ser informativa)
- PDF icon + "Download report (PDF)" → DECORATIVE (redundante)
<button><img alt="Save"></button>→ ACTIVE (contenido único)<button>Save <img alt=""></button>→ DECORATIVE (el texto es suficiente)<input type="image" src="search.png">→ ACTIVE (regla especial, detección Capa 1, incluso sin alt)<input type="image" alt="Search">→ ACTIVE (regla especial, detección Capa 1)<a><img aria-hidden="true"></a>→ DECORATIVE (oculto sobrescribe)<a href="/home">Home <svg></svg></a>(SVG sin alt/aria-label) → DECORATIVE (sin nombre accesible, no agrega información más allá del texto del enlace)- Logo sin alt text/aria-label → DECORATIVE (carece de nombre accesible, no puede ser informativa)
- Logo CON alt text/aria-label → INFORMATIVE (si agrega valor) o DECORATIVE (si es redundante)
- Foto de perro durmiendo + "Un perro duerme pacíficamente" → DECORATIVE (descrito)
- Foto de producto en reseña + alt text → INFORMATIVE (muestra apariencia, tiene nombre accesible)
- Foto de producto en reseña SIN alt text → DECORATIVE (carece de nombre accesible, no puede ser informativa)
Casos Especiales
El prompt incluye manejo detallado de casos especiales:
- SVGs con
aria-hidden="true"→ DECORATIVE (incluso en enlaces/botones) - SVGs sin nombre accesible (sin alt, sin aria-label, sin title) en enlaces/botones etiquetados → DECORATIVE (no puede ser informativa sin nombre accesible, y si no agrega información más allá de la etiqueta, es decorativa)
- Alt vacío en enlaces → DECORATIVE (no ACTIVE, y no puede ser informativa sin nombre accesible)
- Logos sin alt text/aria-label/title → DECORATIVE (carece de nombre accesible, no puede ser informativa)
- Imágenes sin nombre accesible que no agregan información más allá del contexto → DECORATIVE (ej., SVG en enlace que ya tiene etiqueta de texto)
- Múltiples imágenes en control: Clasificar cada una independientemente
- Alt incorrecto en decorativa → Sigue siendo DECORATIVE (recomendar eliminación)
- CRÍTICO: INFORMATIVE REQUIERE NOMBRE ACCESIBLE: Una imagen no puede ser INFORMATIVE si carece de nombre accesible (texto alternativo, aria-label, title, etc.), incluso si parece tener valor de contenido. Clasificar como DECORATIVE.
Formato de Salida
El prompt especifica un formato JSON estricto para la respuesta:
{
"images": [
{
"index": 1,
"backendId": "backend_id_if_available_or_null",
"uniqueId": "unique_id_if_available_or_null",
"classification": "active|informative|decorative",
"confidence": "high|medium|low",
"reasoning": "Explicación concisa (1-2 oraciones), citando pasos/reglas usados (ej., 'Regla 2: input type=\"image\" es siempre ACTIVE')",
"describes_image": true|false,
"alt_text_quality_explanation": "Explicación detallada de si el texto alternativo o nombre accesible describe con precisión el contenido de la imagen y por qué",
"alt_text_quality": "good|needs_improvement|missing",
"accessibility_score": 0-10,
"recommendations": ["Bullet 1", "Bullet 2"] // Array vacío si no hay ninguna
},
...
],
"summary": {
"total_images": N,
"active_count": 0,
"informative_count": 0,
"decorative_count": 0,
"average_accessibility_score": 0.0
}
}Fuentes de Datos Prioritarias
El prompt establece un orden de prioridad para las fuentes de datos:
OuterHTML (PRIORIDAD MÁS ALTA): SIEMPRE parsear outerHTML disponible en orden por capas—muestra atributos HTML/estructura reales. Extraer atributos como
type,alt,aria-hiddendirectamente del string HTML.- Para elementos input: Buscar
type="image"en AMBOSelementOuterHTMLYparentOuterHTML/containerOuterHTMLpara activar ACTIVE (atributo alt no requerido). - Revela si la imagen es contenido único (ACTIVE), redundante (DECORATIVE), o aditivo (INFORMATIVE).
- Verificar atributos directamente (ej.,
aria-hidden,alt,role).
- Para elementos input: Buscar
Ancestro Interactivo: Si está presente, usar para evaluar si la imagen impulsa la interactividad (ej., contenido único de botón → ACTIVE).
HTML Padre/Contenedor: Para contexto no interactivo; evaluar relación con texto/elementos cercanos.
Contenido Visual: Examinar el documento PDF y la captura de pantalla dentro de él—decorativo (formas/patrones) vs. informativo (objetos/datos). Revisar el PDF cuidadosamente para ver la representación visual de cada imagen.
Texto Contextual: Texto cercano en el documento PDF/captura de pantalla/outerHTML; si cubre información de la imagen, → DECORATIVE.
Resumen
El sistema de clasificación de imágenes utiliza un enfoque de múltiples capas que combina:
- Extracción exhaustiva de elementos de imagen desde AXTree y DOM
- Enriquecimiento contextual con información HTML y ancestros interactivos
- Análisis visual mediante IA con un prompt detallado y estructurado
- Aplicación de reglas de prioridad para sobrescribir clasificaciones cuando sea necesario
- Evaluación de calidad del texto alternativo comparándolo con el contenido visual
- Generación de reportes detallados con recomendaciones específicas
El prompt está diseñado para guiar a la IA a través de un proceso sistemático y riguroso que asegura una alta precisión en la clasificación, siguiendo las mejores prácticas de accesibilidad web según WCAG 2.1 y los tutoriales W3C WAI.
